home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 6 / MacMania 6.toast / / Tools&Utilities / EnterAct Stuff / Documentation / hAWK_BuiltIns.h < prev    next >
Text File  |  1996-10-08  |  11KB  |  220 lines
  1. /* hAWK_BuiltIns.h : add this to your EnterAct project and update your
  2. dictionary, then AutoLook will show definitions for hAWK's built-in variables and
  3. string and file functions. The type "hAWK_Builtin" is fictitious.
  4.  
  5. To have a hAWK program eg "$MyProgram" built into your EnterAct dictionary change its
  6. name to "$$MyProgram.awk" and use the "File Extensions..." dialog to add the "awk"
  7. to the left or middle pane (your choice)--then add your hAWK program to your project
  8. and update your dictionary. You'll find the program also has a function marker menu
  9. (option-click in the window's title bar).
  10. */
  11.  
  12. //hAWK's built-in variables are:
  13. hAWK_Builtin ARGC//the number of input files plus one
  14. ;
  15. hAWK_Builtin ARGV /*array of command line arguments. The array is indexed from 0 to
  16. ARGC - 1, the input file names being ARGV[1] through ARGV[ARGC-1]. Dynamically
  17. changing the contents of ARGV can control the files used for data.*/
  18. ;
  19. hAWK_Builtin FILENAME /*the name of the current input file. If no files are specified
  20. on the command line, the value of FILENAME is "-". A hAWK program may do all of its
  21. work in a BEGIN block, with no need for input (generating a list of random numbers
  22. for example).*/
  23. ;
  24. hAWK_Builtin FNR/* the input record number in the current input file. Reset to 1 when
  25. starting a new input file. Hence the pattern “FNR == 1” detects the start of each
  26. file.*/
  27. ;
  28. hAWK_Builtin FS/* the input field separator, a blank by default. If the default FS is
  29. used then leading blanks and tabs are trimmed from $1.*/
  30. ;
  31. hAWK_Builtin IGNORECASE/* controls the case-sensitivity of all regular expression
  32. operations. If IGNORECASE has a non-zero value, then pattern matching in rules,
  33. field splitting with FS , regular expression matching with ~ and !~ , and the gsub()
  34. , index() , match() , split() , and sub() pre-defined functions will all ignore case
  35. when doing regular expression operations. Thus, if IGNORECASE is not equal to zero,
  36. /aB/ matches all of the strings "ab", "aB", "Ab", and "AB". The initial value of
  37. IGNORECASE is zero, so all regular expression operations are normally
  38. case-sensitive.*/
  39. ;
  40. hAWK_Builtin NF// the number of fields in the current input record.
  41. ;
  42. hAWK_Builtin NR// the total number of input records seen so far.
  43. ;
  44. hAWK_Builtin OFMT// the output format for numbers, %.6g by default.
  45. ;
  46. hAWK_Builtin OFS// the output field separator, a blank by default.
  47. ;
  48. hAWK_Builtin ORS// the output record separator, by default a newline.
  49. ;
  50. hAWK_Builtin RS/* the input record separator, by default a newline. RS is exceptional
  51. in that only the first character of its string value is used for separating records.
  52. If RS is set to the null string, then records are separated by blank lines. When RS
  53. is set to the null string, then the newline character always acts as a field
  54. separator, in addition to whatever value FS may have.*/
  55. ;
  56. hAWK_Builtin RSTART// the index of the first character matched by match(); 0 if no match.
  57. ;
  58. hAWK_Builtin RLENGTH// the length of the string matched by match(); -1 if no match.
  59. ;
  60. hAWK_Builtin SUBSEP/* the character used to separate multiple subscripts in array
  61. elements, by default "\034", some kinda up arrow very rare in text.*/
  62. ;
  63. //(and three added for the Macintosh version)
  64. hAWK_Builtin RUNERR/* short for "run error", a file name that you can use to print
  65. your own error messages to, as in
  66.     print "Error during run" > RUNERR.
  67. Default name is $tempRunErr, and you'll find the file in the same folder as
  68. $tempStdOut.*/
  69. ;
  70. hAWK_Builtin STDPATH/* path name that can be prefixed to any file name you wish to be
  71. written to the same folder as stdout ($tempStdOut). Typically looks like
  72.     "Disk:folder1...:folderN:" and typical use looks like
  73.     outname = "MyOutFile"
  74.     fullOutName = STDPATH outname;
  75.     print "something" > fullOutName;*/
  76. ;
  77. hAWK_Builtin TIME// at start of run, eg "Sunday, October 13, 1991 07:58 AM"
  78. ;
  79.  
  80.  
  81.  
  82. //    Built–in string functions
  83. gsub(r, s, t)        /* for each substring matching the regular expression r
  84.                     in the string t , substitutes the string s , and
  85.                     returns the number of substitutions. If t is not
  86.                     supplied, uses $0 . */;
  87. index( s ,  t )        /* returns the index of the string t in the string s,
  88.                     or 0 if t is not present. */;
  89. length( s )            /* returns the length of the string s . */;
  90. match( s , r )        /* returns the position in s where the regular expression r
  91.                     occurs, or 0 if r is not present, and sets the values of
  92.                     RSTART and RLENGTH . */;
  93. split(s, a, r)        /* splits the string s into the array a on the regular
  94.                     expression r , and returns the number of fields. If r is
  95.                     omitted, FS is used instead. */;
  96. sprintf( fmt , expr-list )    /* prints expr-list according to fmt , and returns the
  97.                     resulting string. See the discussion of “printf” for details. */;
  98. sub(r, s,t)         /* this is just like gsub , but only the leftmost matching
  99.                     substring is replaced. Returns number of substitutions. */;
  100. substr(s, i, n)        /* returns the n-character substring of s starting at i . If n
  101.                     is omitted, the rest of s is used. */;
  102. tolower( s )        /* returns a copy of the string s , with all the upper-case
  103.                     characters in s translated to their corresponding
  104.                     lower-case counterparts. Non-alphabetic characters are
  105.                     left unchanged. */;
  106. toupper( s )        /* returns a copy of the string s , with all the lower-case
  107.                     characters in s translated to their corresponding
  108.                     upper-case counterparts. Non-alphabetic characters are
  109.                     left unchanged. */;
  110. lookup ( s )        /* returns integer–coded C type of s (s should be a word).
  111.                     At present this function is supported only by EnterAct.
  112.                     Types are taken from whatever EnterAct project is open
  113.                     at the time. See “$LookupTest” for an example.
  114.                     Type                            integer returned
  115.                     ----                            ------------
  116.                     defined constant or macro        1
  117.                     file–scope variable                2
  118.                     function                        4
  119.                     enum constant                    8
  120.                     typedef                            16
  121.                     struct tag                        32
  122.                     union tag                        64
  123.                     enum tag                        128
  124.                     other                            0 */;
  125. sort(a,b,s)            /* produces an index in the array “b” that can be used to
  126.                     access the elements of “a” in sorted order. The string
  127.                     “s” specifies the kind of sort; "a" for ASCII, "n" for
  128.                     numeric, "d" for dictionary order, and "ra", "rn",
  129.                     "rd" for reverse of the same. Returns the number of
  130.                     elements in the array “b”, which is indexed
  131.                     numerically from 1 upwards. The elements of “b” are
  132.                     the indexes of “a” in sorted order provided “b” is
  133.                     accessed in the sequence b[1], b[2], b[3] etc. Typical
  134.                     use is
  135.                         maxIndex = sort(a, b, "d")
  136.                         for (i = 1; i <= maxIndex; ++i)
  137.                             print a[b[i]]
  138.                     which will print the elements of a in sorted
  139.                     dictionary order. See “$WordFrequency” and
  140.                     “$XRef_Full” for examples, and “$SortTest_Nums” for a
  141.                     simple numeric example. */;
  142. time ( )            /* returns the current time, eg
  143.                         "Sunday, October 27, 1991 09:03:30 AM" 
  144.                     —note this is the time when the function
  145.                     is called, down to the second, whereas the TIME
  146.                     variable holds the time at which your program run
  147.                     starts, down to the minute. See “$TIME” for an example. */;
  148. prompt ( s )        /* displays an OK/Cancel dialog. The string “s” appears
  149.                     at the top of the dialog, and you can type in a string
  150.                     in an edit field. Returns what you type in, as though
  151.                     it was a string constant. Both the string “s” and what
  152.                     you type in are limited to 255 characters. For an
  153.                     example of usage see “$PromptTest” and “$YoungMath”.
  154.                     Typical use is
  155.                         x = prompt("Enter the number of lines to print:")
  156.                         if (x+0 > 0) {
  157.                             while (getline lne > 0 && ++i <= x) print lne }
  158.                     If you cancel the dialog or hit <Return.> without
  159.                     typing in any text, prompt returns the null string "". */;
  160. progress (s)        /* displays the string “s” in a dialog on your screen
  161.                     (the message stays on the screen). You can change the
  162.                     message with another “progress” call. “progress”
  163.                     returns the number of times it has been called, and
  164.                     the dialog goes away by itself at the end of your
  165.                     program run. For a test sample, see “$ProgressTest”. */;
  166.  
  167. //--and added for hAWK version 2 (mainly file functions):
  168. beep( n )        /* does a SysBeep(n); if the duration "n" is <= 0, the menu bar will
  169.                 flash instead. Durations of 0,1,2,5 work best. */;
  170. copy( s, t )    /* copies the file named “s” to the file named “t”. Both file names
  171.                 must be full pathnames (disk:folder:...folder:filename). Either
  172.                 the location or name or both can be changed. If file “t” already
  173.                 exists, it must be closed and unlocked. Both creator and type are
  174.                 preserved, and  the resource fork is copied as well as the data
  175.                 fork. Any kind of file can be copied. To move or rename a file, use 
  176.                     if (copy(s,t)) remove(s)
  177.                 (note this is an efficient way to move a file, but not a very fast
  178.                 way to rename one).
  179.                 Returns 1 if successful, 0 if the copy could not be done. */;
  180. exists( s )        /* returns 1 if the file named “s” exists, 0 if it does not. Any kind
  181.                 of file can be tested. */;
  182. fdate( s )        /* returns date/time of last modification of file named “s”, format
  183.                     “yr:mo:day:hr:min:sec” where yr is 4 digits, and the rest are 2
  184.                 (eg always 01 rather than just 1). The length of the string is
  185.                 always 19 (or 0 if no date could be extracted) and the colons
  186.                 and digits always occupy the same positions. */;
  187. fsize( s )        /* returns size in bytes of the data fork only of the file named “s” */;
  188. getclip( n )    /* returns the calling application’s current clipboard text, up to
  189.                 a maximum of the first “n” bytes. Use n = 0 or omit it entirely
  190.                 if you want the entire clipboard. For example, if the current
  191.                 clip is “Some text here” then getclip(6) returns “Some t”
  192.                 whereas getclip(0) or getclip() returns the entire clip. At
  193.                 present this function is supported by: EnterAct. */;
  194. list( s, a )    /* given file or directory full pathname in “s”, produces list of
  195.                 full pathnames for all TEXT files in the directory (either the
  196.                 directory named or the directory holding the file), as elements
  197.                 indexed 1,2,3... in the array “a”. Note subdirectories are also
  198.                 excluded. Returns the number of files in the list. */;
  199. nested( s, a )    /* given a file full pathname in “s”, generates list of full pathnames
  200.                 for directories at the same level ("sibling folders"); given directory
  201.                 name, generates list of subdirectories at the top level in the named
  202.                 directory (“offspring directories”). The list is returned as elements
  203.                 indexed 1,2,3... in the array “a”. In other words, the same as
  204.                 “list” but for folders rather than TEXT files. Note neither “list”
  205.                 nor “nested” look beneath the top level of the folder in question.
  206.                 Returns the number of directories in the list. */;
  207. remove( s )        /* deletes the file named “s”, provided it is closed and unlocked. Use
  208.                 with caution, this is not undoable unless you get lucky using your
  209.                 favourite file recovery tool. Returns 1 if the file was deleted,
  210.                 0 otherwise. */;
  211. rename( s, t )    /* takes the file with full pathname “s”, and renames it “t”. The
  212.                 new name “t” can be a full pathname, or just the new file name
  213.                 proper, as in 
  214.                     rename("Disk:dir1:aardvark", "Disk:dir1:fruitbat")
  215.                 or equivalently
  216.                     rename("Disk:dir1:aardvark", "fruitbat")
  217.                 This function works only with files, not directories or volumes,
  218.                 returning 1 if the rename was carried out, 0 if not. */;
  219.  
  220.